fix: updated docs styling by lolrobbe2 · Pull Request #2552 · premake/premake-core

lolrobbe2 · 2025-12-02T11:02:38Z

What does this PR do?
this pr aims to rectify #2551

format:

params non determenistic:

for params wich are not deterministic IE have standard values like architecture the following style is used:

`<param_name>` **param_type** - <description>.

params deterministic:

for params wich are deterministic a MD table is used:

for architecture:
arch is the enum/param name

| Arch           | Description                                      |
|-------------|--------------------------------------------------|
| universal    | Universal binaries supported by iOS and macOS    |
| x86            | 32-bit x86 architecture                          |
| x86_64       | 64-bit x86 architecture                          |
| ARM          | 32-bit ARM architecture                          |
| ARM64       | 64-bit ARM architecture                          |
| RISCV64     | 64-bit RISC-V architecture                       |

… (A-C)

Jarod42 · 2025-12-02T14:24:52Z

website/docs/architecture.md


 ```lua
-architecture ("value")
+architecture ("arch")


Both "value"/"arch" are wrong there (not valid value). value/arch would be good (variable might have a correct value)

the idea is to be able to extract the name and get the following:

function architecture(arch) end

It is the quotes that bore me (which shouldn't avoid the name extraction).

Some APIs accept mostly any strings, some quote are OKish, some expect specific string, and providing unexpected ones is confusing IMO.
architecture ("value") was already wrong, and should have been architecture (value) (or architecture ("%{value}")).
And then you should only have renamed 'value' to 'arch'.

Jarod42 · 2025-12-02T14:26:19Z

website/docs/basedir.md

+---
+title: basedir
+description: Sets the base directory for a configuration
+keywords: [premake, basedir, base directory, path, configuration]


Seems you use config in other places

Jarod42 · 2025-12-02T14:28:42Z

website/docs/buildcustomizations.md

+---
+title: buildcustomizations
+description: Imports custom .props files for Visual Studio.
+keywords: [premake, buildcustomizations, visual studio, props, project]


'project' versus 'project config'?

lolrobbe2 · 2025-12-02T22:42:11Z

@Jarod42 maby i should also add a file wich describes the docs styling.

and could you help me figure out a way to enforce this maby via CI?

lolrobbe2 · 2025-12-03T00:58:46Z

@Jarod42 i started work on a js script that cheks the documentation format and logs potential errors and fails when errors are found.

i am also creating a helper script to streamline generating documentation files

Jarod42 · 2025-12-03T08:32:43Z

if you have a script to check documentation, it should probably be called from https://github.com/premake/premake-core/blob/master/.github/workflows/website.yml to ensure consistency.
It just has to return non-zero in case of failure from CI point of view, but messages help humans :-)

lolrobbe2 · 2025-12-03T09:36:12Z

if you have a script to check documentation, it should probably be called from https://github.com/premake/premake-core/blob/master/.github/workflows/website.yml to ensure consistency. It just has to return non-zero in case of failure from CI point of view, but messages help humans :-)

yes that is the goal, it is just a js script so can be run in the website task.

and logs precise errors when things are wrong

KyrietS · 2025-12-04T22:58:14Z

website/docs/callingconvention.md

@@ -1,17 +1,25 @@
+---
+title: callingconvention
+description: Sets whether or not the compiler should build STL modules.


I'm against adding title and description front-matters when they are not necessary. If not set, the title of the page is its filename and it's fine for 99% of our pages. Same goes for description. Docusaurus takes first paragraph as a description so there is no need to repeat it in the front-matter. It's bug-prone and this PR proves it. This description is copied from another page :)

KyrietS · 2025-12-04T23:02:38Z

website/docs/callingconvention.md

+---
+title: callingconvention
+description: Sets whether or not the compiler should build STL modules.
+keywords: [premake, callingconvention, cdecl, fastcall, stdcall, vectorcall, function calling convention, compiler, project config]


What is your algorithm for generating keywords for every page? Do they help you in any way? Because I am pretty much sure they will not affect searchability of our docs at all.

The doccheck script i am working has flagged this and enforces this.

Making the docs uniform will also make readabilty better

By "uniform" you mean adding (a possibly, in my opinion) redundant information to each page and having keywords just for the sake of having them? Because what "compiler" keyword even is? This information is transparent to the reader and it does not affect readability. While I'm happy to uniform the way parameter lists are formatted, I cannot convince myself to having front-matter everywhere just because some script enforces it. Why would it be flagged and enforced in the first place? Why do you think we need this?

nickclark2016 · 2025-12-05T17:35:06Z

I'm not particularly a fan of having multiple things doing the same (or similar) things. Can we not do this in the existing Lua task?

if you have a script to check documentation, it should probably be called from https://github.com/premake/premake-core/blob/master/.github/workflows/website.yml to ensure consistency. It just has to return non-zero in case of failure from CI point of view, but messages help humans :-)

yes that is the goal, it is just a js script so can be run in the website task.

and logs precise errors when things are wrong

lolrobbe2 · 2025-12-05T17:41:47Z

I'm not particularly a fan of having multiple things doing the same (or similar) things. Can we not do this in the existing Lua task?

if you have a script to check documentation, it should probably be called from https://github.com/premake/premake-core/blob/master/.github/workflows/website.yml to ensure consistency. It just has to return non-zero in case of failure from CI point of view, but messages help humans :-)

yes that is the goal, it is just a js script so can be run in the website task.

and logs precise errors when things are wrong

That script just checks that it exists at the moment

nickclark2016 · 2025-12-05T17:48:27Z

I'm not particularly a fan of having multiple things doing the same (or similar) things. Can we not do this in the existing Lua task?

if you have a script to check documentation, it should probably be called from https://github.com/premake/premake-core/blob/master/.github/workflows/website.yml to ensure consistency. It just has to return non-zero in case of failure from CI point of view, but messages help humans :-)

yes that is the goal, it is just a js script so can be run in the website task.
and logs precise errors when things are wrong

That script just checks that it exists at the moment

Why not update the script, rather than creating a new script?

lolrobbe2 · 2025-12-05T17:57:40Z

I'm not particularly a fan of having multiple things doing the same (or similar) things. Can we not do this in the existing Lua task?

if you have a script to check documentation, it should probably be called from https://github.com/premake/premake-core/blob/master/.github/workflows/website.yml to ensure consistency. It just has to return non-zero in case of failure from CI point of view, but messages help humans :-)

yes that is the goal, it is just a js script so can be run in the website task.
and logs precise errors when things are wrong

That script just checks that it exists at the moment

Why not update the script, rather than creating a new script?

Ill look into that. The current scripts are for brainstorming and testing before making it proper.

samsinsane · 2025-12-06T05:52:44Z

I've commented on and closed the referenced issue, I'm going to close this PR too.

fix: updated docs styling for allmodulespublic -> customtoolnamespace…

a797665

… (A-C)

lolrobbe2 changed the title ~~fix: updated docs styling for allmodulespublic -> customtoolnamespace…~~ fix: updated docs styling Dec 2, 2025

fix: removed require for unused plugin

c4f5b85

Jarod42 reviewed Dec 2, 2025

View reviewed changes

KyrietS reviewed Dec 4, 2025

View reviewed changes

feat: added doc generate/check scripts

9dbcad2

samsinsane closed this Dec 6, 2025

Uh oh!

Conversation

lolrobbe2 commented Dec 2, 2025

format:

params non determenistic:

params deterministic:

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lolrobbe2 commented Dec 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

lolrobbe2 commented Dec 3, 2025

Uh oh!

Jarod42 commented Dec 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

lolrobbe2 commented Dec 3, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nickclark2016 commented Dec 5, 2025

Uh oh!

lolrobbe2 commented Dec 5, 2025

Uh oh!

nickclark2016 commented Dec 5, 2025

Uh oh!

lolrobbe2 commented Dec 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

samsinsane commented Dec 6, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

lolrobbe2 commented Dec 2, 2025 •

edited

Loading

Jarod42 commented Dec 3, 2025 •

edited

Loading

lolrobbe2 commented Dec 5, 2025 •

edited

Loading